<iterator>

Iterator definitions

An iterator is any object that, pointing to some element in a range of elements (such as an array or a container), has the ability to iterate through the elements of that range using a set of operators (with at least the increment (++) and dereference (*) operators).

The most obvious form of iterator is a pointer: A pointer can point to elements in an array, and can iterate through them using the increment operator (++). But other kinds of iterators are possible. For example, each container type (such as a list) has a specific iterator type designed to iterate through its elements.

Notice that while a pointer is a form of iterator, not all iterators have the same functionality of pointers; Depending on the properties supported by iterators, they are classified into five different categories:

Iterator categories

Iterators are classified into five categories depending on the functionality they implement:

Input and output iterators are the most limited types of iterators: they can perform sequential single-pass input or output operations.

Forward iterators have all the functionality of input iterators and -if they are not constant iterators- also the functionality of output iterators, although they are limited to one direction in which to iterate through a range (forward). All standard containers support at least forward iterator types.

Bidirectional iterators are like forward iterators but can also be iterated through backwards.

Random-access iterators implement all the functionality of bidirectional iterators, and also have the ability to access ranges non-sequentially: distant elements can be accessed directly by applying an offset value to an iterator without iterating through all the elements in between. These iterators have a similar functionality to standard pointers (pointers are iterators of this category).

The properties of each iterator category are:

category				properties	valid expressions
all categories				copy-constructible, copy-assignable and destructible	`X b(a); b = a;`
all categories				Can be incremented	`++a a++`
Random Access	Bidirectional	Forward	Input	Supports equality/inequality comparisons	`a == b a != b`
			Input	Can be dereferenced as an rvalue	`*a a->m`
			Output	Can be dereferenced as an lvalue (only for mutable iterator types)	`a = t a++ = t`
				default-constructible	`X a; X()`
				Multi-pass: neither dereferencing nor incrementing affects dereferenceability	`{ b=a; a++; b; }`
				Can be decremented	`--a a-- *a--`
				Supports arithmetic operators `+` and `-`	`a + n n + a a - n a - b`
				Supports inequality comparisons (`<`, `>`, `<=` and `>=`) between iterators	`a < b a > b a <= b a >= b`
				Supports compound assignment operations `+=` and `-=`	`a += n a -= n`
				Supports offset dereference operator (`[]`)	`a[n]`

Where X is an iterator type, a and b are objects of this iterator type, t is an object of the type pointed by the iterator type, and n is an integer value.

For more details, see the references for input iterator, output iterator, forward iterator, bidirectional iterator and random-access iterator.

Functions

Iterator operations:

advance: Advance iterator (function template)

distance: Return distance between iterators (function template)

begin: Iterator to beginning (function template)

end: Iterator to end (function template)

prev: Get iterator to previous element (function template)

next: Get iterator to next element (function template)

Iterator generators:

back_inserter: Construct back insert iterator (function template)

front_inserter: Constructs front insert iterator (function template)

inserter: Construct insert iterator (function template)

make_move_iterator: Construct move iterator (function template)

Classes

iterator: Iterator base class (class template)

iterator_traits: Iterator traits (class template)

Predefined iterators

reverse_iterator: Reverse iterator (class template)

move_iterator: Move iterator (class template)

back_insert_iterator: Back insert iterator (class template)

front_insert_iterator: Front insert iterator (class template)

insert_iterator: Insert iterator (class template)

istream_iterator: Istream iterator (class template)

ostream_iterator: Ostream iterator (class template)

istreambuf_iterator: Input stream buffer iterator (class template)

ostreambuf_iterator: Output stream buffer iterator (class template)

Category tags

input_iterator_tag: Input iterator category (class)

output_iterator_tag: Output iterator category (class)

forward_iterator_tag: Forward iterator category (class)

bidirectional_iterator_tag: Bidirectional iterator category (class)

random_access_iterator_tag: Random-access iterator category (class)

functions